<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Importing assets | Butano Docs</title>
  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
  <link rel="stylesheet" href="m-dark+documentation.compiled.css" />
  <link rel="icon" href="favicon-dark.png" type="image/png" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <meta name="theme-color" content="#22272e" />
</head>
<body>
<header><nav id="navigation">
  <div class="m-container">
    <div class="m-row">
      <span id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">
        <a href="https://github.com/GValiente/butano">Butano</a> <span class="m-breadcrumb">|</span> <a href="index.html" class="m-thin">Docs</a>
      </span>
      <div class="m-col-t-4 m-hide-m m-text-right m-nopadr">
        <a href="#search" class="m-doc-search-icon" title="Search" onclick="return showSearch()"><svg style="height: 0.9rem;" viewBox="0 0 16 16">
          <path id="m-doc-search-icon-path" d="m6 0c-3.31 0-6 2.69-6 6 0 3.31 2.69 6 6 6 1.49 0 2.85-0.541 3.89-1.44-0.0164 0.338 0.147 0.759 0.5 1.15l3.22 3.79c0.552 0.614 1.45 0.665 2 0.115 0.55-0.55 0.499-1.45-0.115-2l-3.79-3.22c-0.392-0.353-0.812-0.515-1.15-0.5 0.895-1.05 1.44-2.41 1.44-3.89 0-3.31-2.69-6-6-6zm0 1.56a4.44 4.44 0 0 1 4.44 4.44 4.44 4.44 0 0 1-4.44 4.44 4.44 4.44 0 0 1-4.44-4.44 4.44 4.44 0 0 1 4.44-4.44z"/>
        </svg></a>
        <a id="m-navbar-show" href="#navigation" title="Show navigation"></a>
        <a id="m-navbar-hide" href="#" title="Hide navigation"></a>
      </div>
      <div id="m-navbar-collapse" class="m-col-t-12 m-show-m m-col-m-none m-right-m">
        <div class="m-row">
          <ol class="m-col-t-6 m-col-m-none">
            <li><a href="pages.html">Pages</a></li>
            <li><a href="modules.html">Modules</a></li>
          </ol>
          <ol class="m-col-t-6 m-col-m-none" start="3">
            <li><a href="namespaces.html">Namespaces</a></li>
            <li><a href="annotated.html">Classes</a></li>
            <li><a href="files.html">Files</a></li>
            <li class="m-show-m"><a href="#search" class="m-doc-search-icon" title="Search" onclick="return showSearch()"><svg style="height: 0.9rem;" viewBox="0 0 16 16">
              <use href="#m-doc-search-icon-path" />
            </svg></a></li>
          </ol>
        </div>
      </div>
    </div>
  </div>
</nav></header>
<main><article>
  <div class="m-container m-container-inflatable">
    <div class="m-row">
      <div class="m-col-l-10 m-push-l-1">
        <h1>
          Importing assets
        </h1>
        <nav class="m-block m-default">
          <h3>Contents</h3>
          <ul>
            <li>
              <a href="#import_image">Images</a>
              <ul>
                <li><a href="#import_sprite">Sprites</a></li>
                <li><a href="#import_sprite_tiles">Sprite tiles</a></li>
                <li><a href="#import_sprite_palette">Sprite palettes</a></li>
                <li><a href="#import_regular_bg">Regular backgrounds</a></li>
                <li><a href="#import_regular_bg_tiles">Regular background tiles</a></li>
                <li><a href="#import_affine_bg">Affine backgrounds</a></li>
                <li><a href="#import_affine_bg_tiles">Affine background tiles</a></li>
                <li><a href="#import_bg_palette">Background palettes</a></li>
              </ul>
            </li>
            <li>
              <a href="#import_audio">Audio</a>
              <ul>
                <li><a href="#import_direct_sound_music">Direct Sound music</a></li>
                <li><a href="#import_dmg_music">DMG music</a></li>
                <li><a href="#import_sound">Sound effects</a></li>
              </ul>
            </li>
          </ul>
        </nav>
<p>Importing your graphic and audio files into a GBA game can be annoying, but with Butano and this guide you will be good to go.</p><p>GBA ROMs by themselves don&#x27;t include a file system, so you can&#x27;t put a couple of <code>*.bmp</code> files into a folder and expect to read them directly from the GBA side.</p><p>This means that all the game&#x27;s data has to be added directly to the binary. Don&#x27;t worry, because Butano build system does this for you. When you drop a file into an assets folder, Butano:</p><ul><li>Generates a GBA-friendly version of it.</li><li>Inserts it into the ROM.</li><li>Creates a C++ header into the <code>build</code> folder containing the required information to use the assets with ease.</li></ul><p>Let&#x27;s see how to import image and audio files.</p><section id="import_image"><h2><a href="#import_image">Images</a></h2><p>By default image files go into the <code>graphics</code> folder of your project.</p><p>Butano for now is a little finicky about the images it likes, sorry.</p><p>The required image format is the following:</p><ul><li>BMP without compression or color space information.</li><li>16 or 256 colors only.</li><li>The first color in the color palette is the transparent one, so in most cases it will not be shown on screen.</li></ul><p>If you get an <code>invalid header size</code> error when importing a <code>*.bmp</code> file, it probably means that the image format is not supported.</p><p>If you are using <a href="https://www.gimp.org/">GIMP</a> for your images, remember to disable color space information:</p><img class="m-image" src="import_gimp.png" alt="Image" /><p>However, the recommended tool to ensure that your images are compatible with Butano is <a href="https://github.com/gb-archive/usenti">Usenti</a>:</p><img class="m-image" src="import_usenti.png" alt="Image" /><p>Usenti is a simple bitmap editor for paletted images, it is like the good old Paint but with various palette/color manipulation tools.</p><p>Any program that can generate indexed <code>*.bmp</code> files without weird headers should work. However:</p><ul><li>Usenti works with 15BPP (bits per pixel) colors, like the GBA and unlike most other popular image editors, which work with 24BPP or 32BPP colors. BPP reduction destroys some color gradients, so the images generated by Usenti are closer to what a GBA can display.</li><li>Usenti is powered by <a href="https://github.com/devkitPro/grit">grit</a>, the tool used by Butano to convert images to GBA friendly data. grit doesn&#x27;t support some <code>*.bmp</code> features like compression or some weird headers, so if Usenti displays a <code>*.bmp</code> file without issues, grit should be able to process it successfully.</li></ul><p>If you are not going to use Usenti for your images, at least try to check them with it when they are not displayed as expected.</p><p>A single <code>*.bmp</code> file is not enough to display graphics on the GBA. You must accompany it with a <code>*.json</code> file with the same name specifying if it is a sprite or a background and some more info.</p><p>Let&#x27;s see how to do it.</p><section id="import_sprite"><h3><a href="#import_sprite">Sprites</a></h3><p>An image file can contain multiple sprite images. If it only contains one sprite image, its size must be one of the specified by <a href="classbn_1_1sprite__shape__size.html" class="m-doc">bn::<wbr />sprite_shape_size</a>.</p><p>Multiple sprite images are allowed by layering them right on the horizontal axis and layering them down on the vertical axis:</p><img class="m-image" src="import_sprite.png" alt="Image" /><p>An example of the <code>*.json</code> files required for sprites is the following:</p><pre class="m-code"><span class="p">{</span>
<span class="w">    </span><span class="nt">&quot;type&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;sprite&quot;</span>
<span class="p">}</span></pre><p>The fields for sprites are the following:</p><ul><li><code>&quot;type&quot;</code>: must be <code>&quot;sprite&quot;</code> for sprites.</li><li><code>&quot;width&quot;</code>: optional field which specifies the width of each sprite image in pixels. For example, if the specified width is 32, an image with 128 pixels of width contains 4 sprite images.</li><li><code>&quot;height&quot;</code>: optional field which specifies the height of each sprite image in pixels. For example, if the specified height is 32, an image with 128 pixels of height contains 4 sprite images.</li><li><code>&quot;bpp_mode&quot;</code>: optional field which specifies the bits per pixel of the sprite:<ul><li><code>&quot;bpp_8&quot;</code>: up to 256 colors.</li><li><code>&quot;bpp_4&quot;</code>: up to 16 colors.</li></ul></li><li><code>&quot;colors_count&quot;</code>: optional field which specifies the sprite palette size [1..256].</li><li><code>&quot;tiles_compression&quot;</code>: optional field which specifies the compression of the tiles data:<ul><li><code>&quot;none&quot;</code>: uncompressed data (this is the default option).</li><li><code>&quot;lz77&quot;</code>: LZ77 compressed data.</li><li><code>&quot;run_length&quot;</code>: run-length compressed data.</li><li><code>&quot;huffman&quot;</code>: Huffman compressed data.</li><li><code>&quot;auto&quot;</code>: uses the option which gives the smallest data size.</li><li><code>&quot;auto_no_huffman&quot;</code>: uses the option which gives the smallest data size, excluding &quot;huffman&quot;.</li></ul></li><li><code>&quot;palette_compression&quot;</code>: optional field which specifies the compression of the colors data:<ul><li><code>&quot;none&quot;</code>: uncompressed data (this is the default option).</li><li><code>&quot;lz77&quot;</code>: LZ77 compressed data.</li><li><code>&quot;run_length&quot;</code>: run-length compressed data.</li><li><code>&quot;huffman&quot;</code>: Huffman compressed data.</li><li><code>&quot;auto&quot;</code>: uses the option which gives the smallest data size.</li><li><code>&quot;auto_no_huffman&quot;</code>: uses the option which gives the smallest data size, excluding &quot;huffman&quot;.</li></ul></li><li><code>&quot;compression&quot;</code>: optional field which specifies the compression of the tiles and the colors data:<ul><li><code>&quot;none&quot;</code>: uncompressed data (this is the default option).</li><li><code>&quot;lz77&quot;</code>: LZ77 compressed data.</li><li><code>&quot;run_length&quot;</code>: run-length compressed data.</li><li><code>&quot;huffman&quot;</code>: Huffman compressed data.</li><li><code>&quot;auto&quot;</code>: uses the option which gives the smallest data size.</li><li><code>&quot;auto_no_huffman&quot;</code>: uses the option which gives the smallest data size, excluding &quot;huffman&quot;.</li></ul></li></ul><p>If the conversion process has finished successfully, a <a href="classbn_1_1sprite__item.html" class="m-doc">bn::<wbr />sprite_item</a> should have been generated in the <code>build</code> folder.</p><p>For example, from two files named <code>image.bmp</code> and <code>image.json</code>, a header file named <code>bn_sprite_items_image.h</code> is generated in the <code>build</code> folder.</p><p>You can use this header to create a sprite with only one line of C++ code:</p><pre class="m-code"><span class="cp">#include</span><span class="w"> </span><span class="cpf">&quot;bn_sprite_items_image.h&quot;</span>

<span class="n">bn</span><span class="o">::</span><span class="n">sprite_ptr</span><span class="w"> </span><span class="n">sprite</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">bn</span><span class="o">::</span><span class="n">sprite_items</span><span class="o">::</span><span class="n">image</span><span class="p">.</span><span class="n">create_sprite</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">);</span></pre></section><section id="import_sprite_tiles"><h3><a href="#import_sprite_tiles">Sprite tiles</a></h3><p>An image file can contain multiple sprite tile sets. If it only contains one sprite tile set, the size of the image must be one of the specified by <a href="classbn_1_1sprite__shape__size.html" class="m-doc">bn::<wbr />sprite_shape_size</a>.</p><p>Multiple sprite tile sets are allowed by layering them right on the horizontal axis and layering them down on the vertical axis:</p><img class="m-image" src="import_sprite.png" alt="Image" /><p>An example of the <code>*.json</code> files required for sprite tiles is the following:</p><pre class="m-code"><span class="p">{</span>
<span class="w">    </span><span class="nt">&quot;type&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;sprite_tiles&quot;</span>
<span class="p">}</span></pre><p>The fields for sprite tiles are the following:</p><ul><li><code>&quot;type&quot;</code>: must be <code>&quot;sprite_tiles&quot;</code> for sprite tiles.</li><li><code>&quot;width&quot;</code>: optional field which specifies the width of each sprite tile set in pixels. For example, if the specified width is 32, an image with 128 pixels of width contains 4 sprite tile sets.</li><li><code>&quot;height&quot;</code>: optional field which specifies the height of each sprite tile set in pixels. For example, if the specified height is 32, an image with 128 pixels of height contains 4 sprite tile sets.</li><li><code>&quot;bpp_mode&quot;</code>: optional field which specifies the bits per pixel of the sprite tiles:<ul><li><code>&quot;bpp_8&quot;</code>: up to 256 colors.</li><li><code>&quot;bpp_4&quot;</code>: up to 16 colors.</li></ul></li><li><code>&quot;colors_count&quot;</code>: optional field which specifies the sprite palette size [1..256].</li><li><code>&quot;compression&quot;</code>: optional field which specifies the compression of the tiles data:<ul><li><code>&quot;none&quot;</code>: uncompressed data (this is the default option).</li><li><code>&quot;lz77&quot;</code>: LZ77 compressed data.</li><li><code>&quot;run_length&quot;</code>: run-length compressed data.</li><li><code>&quot;huffman&quot;</code>: Huffman compressed data.</li><li><code>&quot;auto&quot;</code>: uses the option which gives the smallest data size.</li><li><code>&quot;auto_no_huffman&quot;</code>: uses the option which gives the smallest data size, excluding &quot;huffman&quot;.</li></ul></li></ul><p>If the conversion process has finished successfully, a <a href="classbn_1_1sprite__tiles__item.html" class="m-doc">bn::<wbr />sprite_tiles_item</a> should have been generated in the <code>build</code> folder.</p><p>For example, from two files named <code>image.bmp</code> and <code>image.json</code>, a header file named <code>bn_sprite_tiles_items_image.h</code> is generated in the <code>build</code> folder.</p><p>You can use this header to create sprite tiles with only one line of C++ code:</p><pre class="m-code"><span class="cp">#include</span><span class="w"> </span><span class="cpf">&quot;bn_sprite_tiles_items_image.h&quot;</span>

<span class="n">bn</span><span class="o">::</span><span class="n">sprite_tiles_ptr</span><span class="w"> </span><span class="n">sprite_tiles</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">bn</span><span class="o">::</span><span class="n">sprite_tiles_items</span><span class="o">::</span><span class="n">image</span><span class="p">.</span><span class="n">create_tiles</span><span class="p">();</span></pre></section><section id="import_sprite_palette"><h3><a href="#import_sprite_palette">Sprite palettes</a></h3><p>An example of the <code>*.json</code> files required for sprite palettes is the following:</p><pre class="m-code"><span class="p">{</span>
<span class="w">    </span><span class="nt">&quot;type&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;sprite_palette&quot;</span>
<span class="p">}</span></pre><p>The fields for sprite palettes are the following:</p><ul><li><code>&quot;type&quot;</code>: must be <code>&quot;sprite_palette&quot;</code> for sprite palettes.</li><li><code>&quot;bpp_mode&quot;</code>: optional field which specifies the bits per pixel of the sprite palette:<ul><li><code>&quot;bpp_8&quot;</code>: up to 256 colors.</li><li><code>&quot;bpp_4&quot;</code>: up to 16 colors.</li></ul></li><li><code>&quot;colors_count&quot;</code>: optional field which specifies the sprite palette size [1..256].</li><li><code>&quot;compression&quot;</code>: optional field which specifies the compression of the colors data:<ul><li><code>&quot;none&quot;</code>: uncompressed data (this is the default option).</li><li><code>&quot;lz77&quot;</code>: LZ77 compressed data.</li><li><code>&quot;run_length&quot;</code>: run-length compressed data.</li><li><code>&quot;huffman&quot;</code>: Huffman compressed data.</li><li><code>&quot;auto&quot;</code>: uses the option which gives the smallest data size.</li><li><code>&quot;auto_no_huffman&quot;</code>: uses the option which gives the smallest data size, excluding &quot;huffman&quot;.</li></ul></li></ul><p>If the conversion process has finished successfully, a <a href="classbn_1_1sprite__palette__item.html" class="m-doc">bn::<wbr />sprite_palette_item</a> should have been generated in the <code>build</code> folder.</p><p>For example, from two files named <code>image.bmp</code> and <code>image.json</code>, a header file named <code>bn_sprite_palette_items_image.h</code> is generated in the <code>build</code> folder.</p><p>You can use this header to create a sprite palette with only one line of C++ code:</p><pre class="m-code"><span class="cp">#include</span><span class="w"> </span><span class="cpf">&quot;bn_sprite_palette_items_image.h&quot;</span>

<span class="n">bn</span><span class="o">::</span><span class="n">sprite_palette_ptr</span><span class="w"> </span><span class="n">sprite_palette</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">bn</span><span class="o">::</span><span class="n">sprite_palette_items</span><span class="o">::</span><span class="n">image</span><span class="p">.</span><span class="n">create_palette</span><span class="p">();</span></pre></section><section id="import_regular_bg"><h3><a href="#import_regular_bg">Regular backgrounds</a></h3><p>An image file can contain multiple regular backgrounds. The size of a small regular background (which are faster) must be 256x256, 256x512, 512x256 or 512x512 pixels. Big regular backgrounds are slower CPU wise, but can have any width or height multiple of 256 pixels.</p><p>Multiple regular background images are allowed by layering them down on the vertical axis:</p><img class="m-image" src="import_regular_bg.png" alt="Image" /><p>An example of the <code>*.json</code> files required for regular backgrounds is the following:</p><pre class="m-code"><span class="p">{</span>
<span class="w">    </span><span class="nt">&quot;type&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;regular_bg&quot;</span>
<span class="p">}</span></pre><p>The fields for regular backgrounds are the following:</p><ul><li><code>&quot;type&quot;</code>: must be <code>&quot;regular_bg&quot;</code> for regular backgrounds.</li><li><code>&quot;height&quot;</code>: optional field which specifies the height of each regular background in pixels. For example, if the specified height is 256, an image with 1024 pixels of height contains 4 regular backgrounds.</li><li><code>&quot;palette_item&quot;</code>: optional field which specifies the name of the <a href="classbn_1_1bg__palette__item.html" class="m-doc">bn::<wbr />bg_palette_item</a> to use for this background.</li><li><code>&quot;bpp_mode&quot;</code>: optional field which specifies the bits per pixel of the regular background. This field is required if an external <a href="classbn_1_1bg__palette__item.html" class="m-doc">bn::<wbr />bg_palette_item</a> is referenced with <code>&quot;palette_item&quot;</code>:<ul><li><code>&quot;bpp_8&quot;</code>: up to 256 colors.</li><li><code>&quot;bpp_4_auto&quot;</code>: up to 16 colors per <a href="group__tile.html" class="m-doc">tile</a>. Butano tries to quantize the image to fit the color palette into the required one. It is not supported if an external <a href="classbn_1_1bg__palette__item.html" class="m-doc">bn::<wbr />bg_palette_item</a> is referenced with <code>&quot;palette_item&quot;</code>.</li><li><code>&quot;bpp_4_manual&quot;</code>: up to 16 colors per <a href="group__tile.html" class="m-doc">tile</a>. Butano expects that the image color palette is already valid for this mode.</li><li><code>&quot;bpp_4&quot;</code>: <code>&quot;bpp_4_manual&quot;</code> alias.</li></ul></li></ul><p>The default is <code>&quot;bpp_4_manual&quot;</code> for 16 color images and <code>&quot;bpp_8&quot;</code> for 256 color images.</p><ul><li><code>&quot;colors_count&quot;</code>: optional field which specifies the background palette size [1..256].</li><li><code>&quot;repeated_tiles_reduction&quot;</code>: optional field which specifies if repeated tiles must be reduced or not (<code>true</code> by default).</li><li><code>&quot;flipped_tiles_reduction&quot;</code>: optional field which specifies if flipped tiles must be reduced or not (<code>true</code> by default).</li><li><code>&quot;palette_reduction&quot;</code>: optional field which specifies if repeated 16 color palettes must be reduced or not (<code>true</code> by default).</li><li><code>&quot;big&quot;</code>: optional boolean field which specifies if maps generated with this item are big or not. If this field is omitted, big maps are generated only if needed.</li><li><code>&quot;tiles_compression&quot;</code>: optional field which specifies the compression of the tiles data:<ul><li><code>&quot;none&quot;</code>: uncompressed data (this is the default option).</li><li><code>&quot;lz77&quot;</code>: LZ77 compressed data.</li><li><code>&quot;run_length&quot;</code>: run-length compressed data.</li><li><code>&quot;huffman&quot;</code>: Huffman compressed data.</li><li><code>&quot;auto&quot;</code>: uses the option which gives the smallest data size.</li><li><code>&quot;auto_no_huffman&quot;</code>: uses the option which gives the smallest data size, excluding &quot;huffman&quot;.</li></ul></li><li><code>&quot;palette_compression&quot;</code>: optional field which specifies the compression of the colors data:<ul><li><code>&quot;none&quot;</code>: uncompressed data (this is the default option).</li><li><code>&quot;lz77&quot;</code>: LZ77 compressed data.</li><li><code>&quot;run_length&quot;</code>: run-length compressed data.</li><li><code>&quot;huffman&quot;</code>: Huffman compressed data.</li><li><code>&quot;auto&quot;</code>: uses the option which gives the smallest data size.</li><li><code>&quot;auto_no_huffman&quot;</code>: uses the option which gives the smallest data size, excluding &quot;huffman&quot;.</li></ul></li><li><code>&quot;map_compression&quot;</code>: optional field which specifies the compression of the map data:<ul><li><code>&quot;none&quot;</code>: uncompressed data (this is the default option).</li><li><code>&quot;lz77&quot;</code>: LZ77 compressed data.</li><li><code>&quot;run_length&quot;</code>: run-length compressed data.</li><li><code>&quot;huffman&quot;</code>: Huffman compressed data.</li><li><code>&quot;auto&quot;</code>: uses the option which gives the smallest data size.</li><li><code>&quot;auto_no_huffman&quot;</code>: uses the option which gives the smallest data size, excluding &quot;huffman&quot;.</li></ul></li><li><code>&quot;compression&quot;</code>: optional field which specifies the compression of the tiles, the colors and the map data:<ul><li><code>&quot;none&quot;</code>: uncompressed data (this is the default option).</li><li><code>&quot;lz77&quot;</code>: LZ77 compressed data.</li><li><code>&quot;run_length&quot;</code>: run-length compressed data.</li><li><code>&quot;huffman&quot;</code>: Huffman compressed data.</li><li><code>&quot;auto&quot;</code>: uses the option which gives the smallest data size.</li><li><code>&quot;auto_no_huffman&quot;</code>: uses the option which gives the smallest data size, excluding &quot;huffman&quot;.</li></ul></li></ul><p>If the conversion process has finished successfully, a <a href="classbn_1_1regular__bg__item.html" class="m-doc">bn::<wbr />regular_bg_item</a> should have been generated in the <code>build</code> folder.</p><p>For example, from two files named <code>image.bmp</code> and <code>image.json</code>, a header file named <code>bn_regular_bg_items_image.h</code> is generated in the <code>build</code> folder.</p><p>You can use this header to create a regular background with only one line of C++ code:</p><pre class="m-code"><span class="cp">#include</span><span class="w"> </span><span class="cpf">&quot;bn_regular_bg_items_image.h&quot;</span>

<span class="n">bn</span><span class="o">::</span><span class="n">regular_bg_ptr</span><span class="w"> </span><span class="n">regular_bg</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">bn</span><span class="o">::</span><span class="n">regular_bg_items</span><span class="o">::</span><span class="n">image</span><span class="p">.</span><span class="n">create_bg</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">);</span></pre></section><section id="import_regular_bg_tiles"><h3><a href="#import_regular_bg_tiles">Regular background tiles</a></h3><p>An image file can contain up to 1024 regular background tiles.</p><p>An example of the <code>*.json</code> files required for regular background tiles is the following:</p><pre class="m-code"><span class="p">{</span>
<span class="w">    </span><span class="nt">&quot;type&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;regular_bg_tiles&quot;</span><span class="p">,</span>
<span class="w">    </span><span class="nt">&quot;bpp_mode&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;bpp_8&quot;</span>
<span class="p">}</span></pre><p>The fields for regular background tiles are the following:</p><ul><li><code>&quot;type&quot;</code>: must be <code>&quot;regular_bg_tiles&quot;</code> for regular background tiles.</li><li><code>&quot;bpp_mode&quot;</code>: specifies the bits per pixel of the regular background tiles:<ul><li><code>&quot;bpp_8&quot;</code>: up to 256 colors.</li><li><code>&quot;bpp_4&quot;</code>: up to 16 colors per <a href="group__tile.html" class="m-doc">tile</a>. Butano expects that the image color palette is already valid for this mode.</li></ul></li><li><code>&quot;compression&quot;</code>: optional field which specifies the compression of the tiles data:<ul><li><code>&quot;none&quot;</code>: uncompressed data (this is the default option).</li><li><code>&quot;lz77&quot;</code>: LZ77 compressed data.</li><li><code>&quot;run_length&quot;</code>: run-length compressed data.</li><li><code>&quot;huffman&quot;</code>: Huffman compressed data.</li><li><code>&quot;auto&quot;</code>: uses the option which gives the smallest data size.</li><li><code>&quot;auto_no_huffman&quot;</code>: uses the option which gives the smallest data size, excluding &quot;huffman&quot;.</li></ul></li><li><code>&quot;generate_palette&quot;</code>: optional field which specifies if a background palette must be generated (<code>false</code> by default).</li><li><code>&quot;palette_colors_count&quot;</code>: optional field which specifies the background palette size [1..256].</li><li><code>&quot;palette_compression&quot;</code>: optional field which specifies the compression of the colors data:<ul><li><code>&quot;none&quot;</code>: uncompressed data (this is the default option).</li><li><code>&quot;lz77&quot;</code>: LZ77 compressed data.</li><li><code>&quot;run_length&quot;</code>: run-length compressed data.</li><li><code>&quot;huffman&quot;</code>: Huffman compressed data.</li><li><code>&quot;auto&quot;</code>: uses the option which gives the smallest data size.</li><li><code>&quot;auto_no_huffman&quot;</code>: uses the option which gives the smallest data size, excluding &quot;huffman&quot;.</li></ul></li></ul><p>If the conversion process has finished successfully, a <a href="classbn_1_1regular__bg__tiles__item.html" class="m-doc">bn::<wbr />regular_bg_tiles_item</a> should have been generated in the <code>build</code> folder.</p><p>For example, from two files named <code>image.bmp</code> and <code>image.json</code>, a header file named <code>bn_regular_bg_tiles_items_image.h</code> is generated in the <code>build</code> folder.</p><p>You can use this header to create regular background tiles with only one line of C++ code:</p><pre class="m-code"><span class="cp">#include</span><span class="w"> </span><span class="cpf">&quot;bn_regular_bg_tiles_items_image.h&quot;</span>

<span class="n">bn</span><span class="o">::</span><span class="n">regular_bg_tiles_ptr</span><span class="w"> </span><span class="n">regular_bg_tiles</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">bn</span><span class="o">::</span><span class="n">regular_bg_tiles_items</span><span class="o">::</span><span class="n">image</span><span class="p">.</span><span class="n">create_tiles</span><span class="p">();</span></pre></section><section id="import_affine_bg"><h3><a href="#import_affine_bg">Affine backgrounds</a></h3><p>An image file can contain multiple affine backgrounds. The size of a small affine background (which are faster) must be 128x128, 256x256, 512x512 or 1024x1024 pixels. Big affine backgrounds are slower CPU wise, but can have any width or height multiple of 256 pixels.</p><p>Multiple affine background images are allowed by layering them down on the vertical axis:</p><img class="m-image" src="import_affine_bg.png" alt="Image" /><p>An example of the <code>*.json</code> files required for affine backgrounds is the following:</p><pre class="m-code"><span class="p">{</span>
<span class="w">    </span><span class="nt">&quot;type&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;affine_bg&quot;</span>
<span class="p">}</span></pre><p>The fields for affine backgrounds are the following:</p><ul><li><code>&quot;type&quot;</code>: must be <code>&quot;affine_bg&quot;</code> for affine backgrounds.</li><li><code>&quot;height&quot;</code>: optional field which specifies the height of each affine background in pixels. For example, if the specified height is 256, an image with 1024 pixels of height contains 4 affine backgrounds.</li><li><code>&quot;palette_item&quot;</code>: optional field which specifies the name of the <a href="classbn_1_1bg__palette__item.html" class="m-doc">bn::<wbr />bg_palette_item</a> to use for this background.</li><li><code>&quot;colors_count&quot;</code>: optional field which specifies the background palette size [1..256].</li><li><code>&quot;repeated_tiles_reduction&quot;</code>: optional field which specifies if repeated tiles must be reduced or not (<code>true</code> by default).</li><li><code>&quot;big&quot;</code>: optional boolean field which specifies if maps generated with this item are big or not. If this field is omitted, big maps are generated only if needed.</li><li><code>&quot;tiles_compression&quot;</code>: optional field which specifies the compression of the tiles data:<ul><li><code>&quot;none&quot;</code>: uncompressed data (this is the default option).</li><li><code>&quot;lz77&quot;</code>: LZ77 compressed data.</li><li><code>&quot;run_length&quot;</code>: run-length compressed data.</li><li><code>&quot;huffman&quot;</code>: Huffman compressed data.</li><li><code>&quot;auto&quot;</code>: uses the option which gives the smallest data size.</li><li><code>&quot;auto_no_huffman&quot;</code>: uses the option which gives the smallest data size, excluding &quot;huffman&quot;.</li></ul></li><li><code>&quot;palette_compression&quot;</code>: optional field which specifies the compression of the colors data:<ul><li><code>&quot;none&quot;</code>: uncompressed data (this is the default option).</li><li><code>&quot;lz77&quot;</code>: LZ77 compressed data.</li><li><code>&quot;run_length&quot;</code>: run-length compressed data.</li><li><code>&quot;huffman&quot;</code>: Huffman compressed data.</li><li><code>&quot;auto&quot;</code>: uses the option which gives the smallest data size.</li><li><code>&quot;auto_no_huffman&quot;</code>: uses the option which gives the smallest data size, excluding &quot;huffman&quot;.</li></ul></li><li><code>&quot;map_compression&quot;</code>: optional field which specifies the compression of the map data:<ul><li><code>&quot;none&quot;</code>: uncompressed data (this is the default option).</li><li><code>&quot;lz77&quot;</code>: LZ77 compressed data.</li><li><code>&quot;run_length&quot;</code>: run-length compressed data.</li><li><code>&quot;huffman&quot;</code>: Huffman compressed data.</li><li><code>&quot;auto&quot;</code>: uses the option which gives the smallest data size.</li><li><code>&quot;auto_no_huffman&quot;</code>: uses the option which gives the smallest data size, excluding &quot;huffman&quot;.</li></ul></li><li><code>&quot;compression&quot;</code>: optional field which specifies the compression of the tiles, the colors and the map data:<ul><li><code>&quot;none&quot;</code>: uncompressed data (this is the default option).</li><li><code>&quot;lz77&quot;</code>: LZ77 compressed data.</li><li><code>&quot;run_length&quot;</code>: run-length compressed data.</li><li><code>&quot;huffman&quot;</code>: Huffman compressed data.</li><li><code>&quot;auto&quot;</code>: uses the option which gives the smallest data size.</li><li><code>&quot;auto_no_huffman&quot;</code>: uses the option which gives the smallest data size, excluding &quot;huffman&quot;.</li></ul></li></ul><p>If the conversion process has finished successfully, a <a href="classbn_1_1affine__bg__item.html" class="m-doc">bn::<wbr />affine_bg_item</a> should have been generated in the <code>build</code> folder.</p><p>For example, from two files named <code>image.bmp</code> and <code>image.json</code>, a header file named <code>bn_affine_bg_items_image.h</code> is generated in the <code>build</code> folder.</p><p>You can use this header to create an affine background with only one line of C++ code:</p><pre class="m-code"><span class="cp">#include</span><span class="w"> </span><span class="cpf">&quot;bn_affine_bg_items_image.h&quot;</span>

<span class="n">bn</span><span class="o">::</span><span class="n">affine_bg_ptr</span><span class="w"> </span><span class="n">affine_bg</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">bn</span><span class="o">::</span><span class="n">affine_bg_items</span><span class="o">::</span><span class="n">image</span><span class="p">.</span><span class="n">create_bg</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">);</span></pre></section><section id="import_affine_bg_tiles"><h3><a href="#import_affine_bg_tiles">Affine background tiles</a></h3><p>An image file can contain up to 256 affine background tiles.</p><p>An example of the <code>*.json</code> files required for affine background tiles is the following:</p><pre class="m-code"><span class="p">{</span>
<span class="w">    </span><span class="nt">&quot;type&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;affine_bg_tiles&quot;</span>
<span class="p">}</span></pre><p>The fields for affine background tiles are the following:</p><ul><li><code>&quot;type&quot;</code>: must be <code>&quot;affine_bg_tiles&quot;</code> for affine background tiles.</li><li><code>&quot;compression&quot;</code>: optional field which specifies the compression of the tiles data:<ul><li><code>&quot;none&quot;</code>: uncompressed data (this is the default option).</li><li><code>&quot;lz77&quot;</code>: LZ77 compressed data.</li><li><code>&quot;run_length&quot;</code>: run-length compressed data.</li><li><code>&quot;huffman&quot;</code>: Huffman compressed data.</li><li><code>&quot;auto&quot;</code>: uses the option which gives the smallest data size.</li><li><code>&quot;auto_no_huffman&quot;</code>: uses the option which gives the smallest data size, excluding &quot;huffman&quot;.</li></ul></li><li><code>&quot;generate_palette&quot;</code>: optional field which specifies if a background palette must be generated (<code>false</code> by default).</li><li><code>&quot;palette_colors_count&quot;</code>: optional field which specifies the background palette size [1..256].</li><li><code>&quot;palette_compression&quot;</code>: optional field which specifies the compression of the colors data:<ul><li><code>&quot;none&quot;</code>: uncompressed data (this is the default option).</li><li><code>&quot;lz77&quot;</code>: LZ77 compressed data.</li><li><code>&quot;run_length&quot;</code>: run-length compressed data.</li><li><code>&quot;huffman&quot;</code>: Huffman compressed data.</li><li><code>&quot;auto&quot;</code>: uses the option which gives the smallest data size.</li><li><code>&quot;auto_no_huffman&quot;</code>: uses the option which gives the smallest data size, excluding &quot;huffman&quot;.</li></ul></li></ul><p>If the conversion process has finished successfully, a <a href="classbn_1_1affine__bg__tiles__item.html" class="m-doc">bn::<wbr />affine_bg_tiles_item</a> should have been generated in the <code>build</code> folder.</p><p>For example, from two files named <code>image.bmp</code> and <code>image.json</code>, a header file named <code>bn_affine_bg_tiles_items_image.h</code> is generated in the <code>build</code> folder.</p><p>You can use this header to create affine background tiles with only one line of C++ code:</p><pre class="m-code"><span class="cp">#include</span><span class="w"> </span><span class="cpf">&quot;bn_affine_bg_tiles_items_image.h&quot;</span>

<span class="n">bn</span><span class="o">::</span><span class="n">affine_bg_tiles_ptr</span><span class="w"> </span><span class="n">affine_bg_tiles</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">bn</span><span class="o">::</span><span class="n">affine_bg_tiles_items</span><span class="o">::</span><span class="n">image</span><span class="p">.</span><span class="n">create_tiles</span><span class="p">();</span></pre></section><section id="import_bg_palette"><h3><a href="#import_bg_palette">Background palettes</a></h3><p>An example of the <code>*.json</code> files required for background palettes is the following:</p><pre class="m-code"><span class="p">{</span>
<span class="w">    </span><span class="nt">&quot;type&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;bg_palette&quot;</span><span class="p">,</span>
<span class="w">    </span><span class="nt">&quot;bpp_mode&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;bpp_8&quot;</span>
<span class="p">}</span></pre><p>The fields for background palettes are the following:</p><ul><li><code>&quot;type&quot;</code>: must be <code>&quot;bg_palette&quot;</code> for background palettes.</li><li><code>&quot;bpp_mode&quot;</code>: specifies the bits per pixel of the background palette:<ul><li><code>&quot;bpp_8&quot;</code>: up to 256 colors.</li><li><code>&quot;bpp_4&quot;</code>: up to 16 colors per <a href="group__tile.html" class="m-doc">tile</a>.</li></ul></li><li><code>&quot;colors_count&quot;</code>: optional field which specifies the background palette size [1..256].</li><li><code>&quot;compression&quot;</code>: optional field which specifies the compression of the colors data:<ul><li><code>&quot;none&quot;</code>: uncompressed data (this is the default option).</li><li><code>&quot;lz77&quot;</code>: LZ77 compressed data.</li><li><code>&quot;run_length&quot;</code>: run-length compressed data.</li><li><code>&quot;huffman&quot;</code>: Huffman compressed data.</li><li><code>&quot;auto&quot;</code>: uses the option which gives the smallest data size.</li><li><code>&quot;auto_no_huffman&quot;</code>: uses the option which gives the smallest data size, excluding &quot;huffman&quot;.</li></ul></li></ul><p>If the conversion process has finished successfully, a <a href="classbn_1_1bg__palette__item.html" class="m-doc">bn::<wbr />bg_palette_item</a> should have been generated in the <code>build</code> folder.</p><p>For example, from two files named <code>image.bmp</code> and <code>image.json</code>, a header file named <code>bn_bg_palette_items_image.h</code> is generated in the <code>build</code> folder.</p><p>You can use this header to create a background palette with only one line of C++ code:</p><pre class="m-code"><span class="cp">#include</span><span class="w"> </span><span class="cpf">&quot;bn_bg_palette_items_image.h&quot;</span>

<span class="n">bn</span><span class="o">::</span><span class="n">bg_palette_ptr</span><span class="w"> </span><span class="n">bg_palette</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">bn</span><span class="o">::</span><span class="n">bg_palette_items</span><span class="o">::</span><span class="n">image</span><span class="p">.</span><span class="n">create_palette</span><span class="p">();</span></pre></section></section><section id="import_audio"><h2><a href="#import_audio">Audio</a></h2><p>By default audio files played with Direct Sound channels go into the <code>audio</code> folder of your project, and music files played with DMG channels go into the <code>dmg_audio</code> folder.</p><p>By default, Direct Sound stuff is managed by the awesome <a href="https://blocksds.skylyrac.net/docs/maxmod/index.html">Maxmod</a>, so if you have an issue with Direct Sound music or with sound effects, well, you know.</p><p>DMG channels are handled by the also impressive <a href="https://github.com/AntonioND/gbt-player">GBT Player</a> and <a href="https://github.com/copyrat90/gbadev-ja-test">VGM player</a>, so if you have issues with DMG music, you know where to go.</p><p>A really nice application for editing audio files before importing them into your game is <a href="https://openmpt.org/">OpenMPT</a>.</p><section id="import_direct_sound_music"><h3><a href="#import_direct_sound_music">Direct Sound music</a></h3><p>The required format for Direct Sound music is module files with <code>*.mod</code>, <code>*.xm</code>, <code>*.s3m</code> and <code>*.it</code> extensions. If you&#x27;re using <a href="https://github.com/stuij/apex-audio-system">Apex Audio System</a> instead of the default audio backend (<a href="https://blocksds.skylyrac.net/docs/maxmod/index.html">Maxmod</a>), only module files with <code>*.mod</code> extension are allowed.</p><p>By default Butano supports up to 16 music channels, but this limit can be increased by overloading the definition of <a href="group__music.html#ga9ec36de1eb7cd32376a5765bf3d6a63d" class="m-doc">BN_<wbr />CFG_<wbr />AUDIO_<wbr />MAX_<wbr />MUSIC_<wbr />CHANNELS</a>.</p><p>However, don&#x27;t do it if you can, don&#x27;t make the poor GBA suffer.</p><p>If the conversion process has finished successfully, a bunch of <a href="classbn_1_1music__item.html" class="m-doc">bn::<wbr />music_item</a> objects under the <code>bn::music_items</code> namespace should have been generated in the <code>build</code> folder for all music files. You can use these items to play music with only one line of C++ code:</p><pre class="m-code"><span class="cp">#include</span><span class="w"> </span><span class="cpf">&quot;bn_music_items.h&quot;</span>

<span class="n">bn</span><span class="o">::</span><span class="n">music_items</span><span class="o">::</span><span class="n">song</span><span class="p">.</span><span class="n">play</span><span class="p">();</span></pre></section><section id="import_dmg_music"><h3><a href="#import_dmg_music">DMG music</a></h3><p>The required format for DMG music is module files with <code>*.mod</code>, <code>*.s3m</code> and <code>*.vgm</code> extensions.</p><p>The recommended way to generate <code>*.vgm</code> compatible files is to use <a href="https://github.com/SuperDisk/hUGETracker">hUGETracker 1.01</a> with timer based tempo disabled:</p><img class="m-image" src="import_hugetracker.png" alt="Image" /><p>If the conversion process has finished successfully, a <a href="classbn_1_1dmg__music__item.html" class="m-doc">bn::<wbr />dmg_music_item</a> should have been generated in the <code>build</code> folder.</p><p>For example, from a file named <code>module.mod</code>, a header file named <code>bn_dmg_music_items_module.h</code> is generated in the <code>build</code> folder.</p><p>You can use this header to play the module file with only one line of C++ code:</p><pre class="m-code"><span class="cp">#include</span><span class="w"> </span><span class="cpf">&quot;bn_dmg_music_items_module.h&quot;</span>

<span class="n">bn</span><span class="o">::</span><span class="n">dmg_music_items</span><span class="o">::</span><span class="k">module</span><span class="p">.</span><span class="n">play</span><span class="p">();</span></pre><p>You can accompany DMG music module files with a <code>*.json</code> file with the same name to specify import options.</p><p>An example of the <code>*.json</code> files for DMG music module files is the following:</p><pre class="m-code"><span class="p">{</span>
<span class="w">    </span><span class="nt">&quot;import_instruments&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
<span class="w">    </span><span class="nt">&quot;mod_speed_conversion&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
<span class="p">}</span></pre><p>Available fields are the following:</p><ul><li><code>&quot;import_instruments&quot;</code>: optional field which specifies if channel 3 instruments must be imported when importing <code>*.s3m</code> module files, replacing the default instruments of GBT Player (<code>false</code> by default). This option is ignored when importing audio files with <code>*.mod</code> and <code>*.vgm</code> extensions.</li><li><code>&quot;mod_speed_conversion&quot;</code>: optional field which specifies if module files with <code>*.mod</code> extension speed must be converted from 50Hz to 60Hz (<code>true</code> by default). This option is ignored when importing audio files with <code>*.s3m</code> and <code>*.vgm</code> extensions.</li></ul><p>The default DMG music master volume is set to 25% ( <a href="group__dmg__music.html#ggab1b4b1b30155d7f77c1cac93f61179b2a2127749533f087678c2ff775d060024e" class="m-doc">bn::<wbr />dmg_music_master_volume::<wbr />QUARTER</a> ). If it sounds too quiet for you, you can change it via <a href="namespacebn_1_1dmg__music.html#a55a100af3c116115bc03a2f57370eefd" class="m-doc">bn::<wbr />dmg_music::<wbr />set_master_volume</a>.</p></section><section id="import_sound"><h3><a href="#import_sound">Sound effects</a></h3><p>The required format for sound effects is waveform audio files (files with <code>*.wav</code> extension) without compression or anything weird. Besides, <em>I think</em> stereo files are not allowed.</p><p>The recommended quality for sound effects is 8-bits 22050 Hz.</p><p>If the conversion process has finished successfully, a bunch of <a href="classbn_1_1sound__item.html" class="m-doc">bn::<wbr />sound_item</a> objects under the <code>bn::sound_items</code> namespace should have been generated in the <code>build</code> folder for all sound files. You can use these items to play sound effects with only one line of C++ code:</p><pre class="m-code"><span class="cp">#include</span><span class="w"> </span><span class="cpf">&quot;bn_sound_items.h&quot;</span>

<span class="n">bn</span><span class="o">::</span><span class="n">sound_items</span><span class="o">::</span><span class="n">sfx</span><span class="p">.</span><span class="n">play</span><span class="p">();</span></pre></section></section>
      </div>
    </div>
  </div>
</article></main>
<div class="m-doc-search" id="search">
  <a href="#!" onclick="return hideSearch()"></a>
  <div class="m-container">
    <div class="m-row">
      <div class="m-col-m-8 m-push-m-2">
        <div class="m-doc-search-header m-text m-small">
          <div><span class="m-label m-default">Tab</span> / <span class="m-label m-default">T</span> to search, <span class="m-label m-default">Esc</span> to close</div>
          <div id="search-symbolcount">&hellip;</div>
        </div>
        <div class="m-doc-search-content">
          <form>
            <input type="search" name="q" id="search-input" placeholder="Loading &hellip;" disabled="disabled" autofocus="autofocus" autocomplete="off" spellcheck="false" />
          </form>
          <noscript class="m-text m-danger m-text-center">Unlike everything else in the docs, the search functionality <em>requires</em> JavaScript.</noscript>
          <div id="search-help" class="m-text m-dim m-text-center">
            <p class="m-noindent">Search for symbols, directories, files, pages or
            modules. You can omit any prefix from the symbol or file path; adding a
            <code>:</code> or <code>/</code> suffix lists all members of given symbol or
            directory.</p>
            <p class="m-noindent">Use <span class="m-label m-dim">&darr;</span>
            / <span class="m-label m-dim">&uarr;</span> to navigate through the list,
            <span class="m-label m-dim">Enter</span> to go.
            <span class="m-label m-dim">Tab</span> autocompletes common prefix, you can
            copy a link to the result using <span class="m-label m-dim">⌘</span>
            <span class="m-label m-dim">L</span> while <span class="m-label m-dim">⌘</span>
            <span class="m-label m-dim">M</span> produces a Markdown link.</p>
          </div>
          <div id="search-notfound" class="m-text m-warning m-text-center">Sorry, nothing was found.</div>
          <ul id="search-results"></ul>
        </div>
      </div>
    </div>
  </div>
</div>
<script src="search-v2.js"></script>
<script src="searchdata-v2.js" async="async"></script>
<footer><nav>
  <div class="m-container">
    <div class="m-row">
      <div class="m-col-l-10 m-push-l-1">
        <p>Butano Docs. Created with <a href="https://doxygen.org/">Doxygen</a> 1.14.0 and <a href="https://mcss.mosra.cz/">m.css</a>.</p>
      </div>
    </div>
  </div>
</nav></footer>
</body>
</html>
